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About This Book 



The OS/2 2.0 Bidirectional National Language Support Programming Reference is a detailed 
reference for application programmers creating programs using bidirectional languages. 

The reference does not give guidance on how to use the functions, nor does it contain information 
about how the functions are related to each other. 



Prerequisite Knowledge 

The OS/2 2.0 Technical Library is intended for professional application developers knowledgeable in 
at least one programming language in which OS/2 programs can be written. You should understand 
the OS/2 services available to users. 



Related Publications 

The National Language Information and Design Guide Volume 3 (SE09-8003) and Volume 4 
(SE09-8004) provide general information about languages that are written right-to-left, and about the 
countries where these languages are used. 
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Chapter 1. Introduction 



The purpose of this reference is to provide information about bidirectional functions, parameters, 
return codes, and constants of the OS/2' 2.0 operating system (for full screen sessions). This chapter 
provides information about the notation conventions and function descriptions used in this reference. 
All bidirectional functions are 16 bit. 

The functions can be used in full-screen sessions to perform basic bidirectional functions. 

An example in C language is shown at the end of each function. 



Conventions Used in Function Descriptions 

The documentation of each function contains these sections: 

Function name 

The function name is listed in alphabetical order at the top of each page, followed by a brief 
description of the function. 

Parameters 

Each parameter is listed with its C language data type, parameter type, and a brief description: 

• All data types are written in uppercase. A data type of 'Pxxxxxxx' implicitly defines a 
pointer to the data type 'xxxxxxx'. 

The term NULL applied to a parameter indicates the presence of the parameter, but with 
no value. 

• There are three parameter types: 

Input 

Specified by the programmer 

Output 

Returned by the operating system 

Input/Output 

Specified by the programmer and modified by the operating system 

• A brief description is provided with each parameter. Where appropriate, restrictions are 
also included. In some cases, the parameter points to a structure. 

Returns 

A list of possible return codes or errors (when appropriate) is included in this section. Some 
functions do not have return codes. 

Remarks 

This section contains additional information about the function, when required. 

Example Code 

An example is shown in C language for each function. 

Programming Note: The names for the functions in this book are shown in mixed-case for 

readability, but are known to the system as uppercase character strings. If you are using a 
compiler that generates a mixed-case external name, you must code the functions in 
uppercase. 



* Trademark of the IBM Corporation. 
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Programming Overview 

A set of bidirectional attributes is provided to allow processing of text in different ways. In addition, 
you are able to view and update these attributes to define the desired level of bidirectional national 
language support (NLS). 

The bidirectional functions cover three main sections: 

• Controlling the screen, keyboard, and printer, bidirectional attributes 

When programming bidirectional-aware applications, you will need to know the current 
bidirectional attributes and be able to change them. Functions are available that query and set 
these attributes. 

• Shaping 

Functions are available for you to handle different cases of online editing, inserting, deleting of 
characters, shaping of character strings, and with specific shape selection. 

• Numerical processing 

Provides for conversion of numerical shapes. 
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Chapter 2. Bidirectional Functions 



Following Is a summary of the bidirectional functions that you can use in your OS/2 16 bit full-screen 
application. 

NIsConvertBidiStrlng 

Converts a bidirectional string with one set of bidirectional attributes to a string with another set 
of bidirectional attributes. 

NIsEdltShape 

Shapes the specified input character or characters with several invocations according to the 
CSD byte in the bidirectional attributes bit mask. 

NlsinverseStrlng 

Places the source string in inverse order into the target string. 

NIsQueryBidiAtt 

Returns the bidirectional information about this session. 

NIsSetBidiAtt 

Sets the bidirectional information for this session. 

NIsSetBidiPrint 

Assigns the bidirectional attributes to a specified printer, and adds the appropriate printer 
codes to override the current bidirectional attributes of the printer. 

NIsShapeBidiStrlng 

Shapes a text string according to the value of the CSD byte in the bidirectional attributes bit 
mask. 
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NIsConvertBidiNumerics 



#define INCL_BDCALLS 



NIsConvertBidiNumerics (BidlAtts, Reserved, Source, Target, Length, Increment) 



NIsConvertBidiNumerics converts a set of numerical values to the proper character form of 
representation defined by the bidirectional attributes for this session. 



Parameters 

BidlAtts (ULONG) - input 

This parameter is a bit mask containing the possible bidirectional attributes. See “Bidirectional 
Attributes Bit Mask” on page 2-22 for mask values. 

Reserved (ULONG) - input 
Must be zero. 

Source (PCHAR) - input 

Address of the source buffer containing the numeric text to be converted. 

Target (PCHAR) - output 

Address of the target buffer where the converted numeric text is written. 

Length (ULONG) - input 

The number of bytes of both the Source and Target buffers (both buffers must be the same 
length). 

Increment (ULONG) - input 

The size in bytes of each character cell. (It will be greater than one when each character byte is 
followed by one or more attributes. Increment is one when characters occupy consecutive 
positions in memory.) 



Returns 

Return code (APIRET). NIsConvertBidiNumerics returns the following values: 

0 NO_ERROR 

671 ERROR_BIDI_INVALID_LENGTH 

672 ERROR_BIDI_INVALID_INCREMENT 

673 ERROR_BIDI_INVALID_COMBINATION 

674 ERROR_BIDI_INVALID_RESERVED 

681 ERROR_BIDI_INVALID_NUM_SHAPE 

Remarks 

The provided data buffers (Source and Target) must not partially overlap, or unpredictable results 
may occur. However, Target and Source may totally overlap. 

Note: The Arabic numerals are defined to be code points (hex 30 to hex 39) and they are also called 
“true numerics". The Hindi numerals are defined to be code points (hex BO to hex B9) and 
they are called “false numerics”. 
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NIsConvertBidiNumerics 



Example Code 

Idefine INCL_D0SERR0RS 

Idefine INCL_BDCALLS /* This is to include the Bidi headers */ 
linclude <os2.h> 

static char num_array[]={'l' , '2' , '3' , '4' , '5‘ , '\0'}; 

CHAR num_back [6] ; 

API RET RC; 

/* Use the OR operator to compose the initial value of */ 

/* the bidi attributes, the value of the numerics is */ 

/* now equal to Hindi. */ 

ULONG bidi_att = BD_LEVEL 
| BD_SUPPORT 
I BDORI ENT_LTR 
| BDNUM_HINDU 
| BDCSD_PASSTHRU ; 

APIRET RC=0; 

ULONG effect = 0; 

ULONG increment = 1; 

ULONG length = 5; 

/* This API will convert the Arabic */ 

/* numerics string to Hindi ones. */ 

RC = NIsConvertBidiNumerics (bidi_att, 

effect , 

num_array, 

num_back, 

length, 

increment); 

if (RC ! =0) 
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NIsConvertBidiString 



#define INCL_BDCALLS 



NIsConvertBidiString (Source, Target, Length, Increment, SBidiAtts, TBidiAtts, Reserved) 



NIsConvertBidiString converts a bidirectional string with one set of bidirectional attributes to a string 
with another set of bidirectional attributes. 

Parameters 

Source (PCHAR) - input 

Address of the source buffer containing the text to be converted. 

Target (PCHAR) - output 

Address of the target buffer where the converted text is written. 

Length (ULONG) - input 

The number of bytes of both the Source and Target buffers. (Both buffers must be the same 
length.) 

Increment (ULONG) - input 

The number of bytes of each character cell. 

SBidiAtts (ULONG) - input 

A bit mask containing the current bidirectional attributes for the source string. See 
“Bidirectional Attributes Bit Mask” on page 2-22 for mask values. 

TBidiAtts (ULONG) - input 

A bit mask containing the needed bidirectional attributes for the target string. See “Bidirectional 
Attributes Bit Mask” on page 2-22 for mask values. 

Reserved (ULONG) - input 
Must be zero. 



Returns 

Return Code (APIRET). NIsConvertBidiString returns the following values: 

0 NO_ERROR 

671 ERROR_BIDI_INVALID_LENGTH 

673 ERROR_BIDI_INVALID_COMBINATION 

674 ERROR_BIDI_INVALID_RESERVED 

678 ERROR_BIDI_INVALID_LEVEL 

679 ERROR_BIDI_INVALID_TYPE_SUPPORT 

680 ERROR_BIDI_INVALID_ORIENTATION 

681 ERROR_BIDI_INVALID_NUM_SHAPE 

682 ERROR_BIDI_INVALID_CSD 



2-4 



Bidirectional National Language Support 








NIsConvertBidiString 



Example Code 

Idefine INCL_D0SERR0RS 

Idefine INCL_BDCALLS /* This is to include the Bidi headers */ 

linclude <os2.h> 

API RET RC; 

/* Input string to be converted */ 

static CHAR string [] = { 1 A' , V , 'a' , 'b' , 'i 1 , 1 c 1 , '2'}; 

ULONG Current_attr; /* Bidi attributes of the source string */ 

ULONG To_attr; /* Bidi attributes of the target string */ 

ULONG reserved=OL; /* reserved */ 

CHAR target [7]; /* Shaped string is returned here */ 

ULONG length=7; /* length of string to be converted */ 

ULONG increment=lL; /* number of bytes to increment between */ 

/* each char*/ 

Current_attr = BD_LEVEL /* reserved */ 

| BD_SUPPORT /* reserved */ 

I BDORIENT_RTL /* The input string is stored RTL */ 

| BDNUM_PASSTHRU /* The numerics are not processed */ 

j BDCSD_PASSTHRU; /* The characters are not shaped */ 

To_attr = BD_LEVEL /* reserved */ 

| BD_SUPPORT /* reserved */ 

I BDORIENT_LTR /* The output is needed to be LTR */ 

I BDNUM_HINDU /* Conversion of numerics to hindi */ 

I BDCSD_AUTOMATIC; /* Automatic Shape determination is */ 

/* requested */ 

/* This call will convert the string from the Current_attr to the */ 

/* To_attr. */ 

RC = NIsConvertBidiString ( string, 

target, 

length, 

increment, 

Current_attr, 

To_attr, 
reserved) ; 

if ( RC! =0) 

printf("RC=%ld\n" ,RC) ; 
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NIsEditShape 



#define INCL_BDCALLS 



NIsEditShape (BidiAtts, Effect, Source, Target, CSDState, Increment) 



NIsEditShape shapes the specified input character or characters with several invocations according 
to the CSD byte in the bidirectional attributes bit mask. 



Parameters 

BidiAtts (ULONG) - input 

This parameter is a bit mask containing the possible bidirectional attributes. See “Bidirectional 
Attributes Bit Mask” on page 2-22 for mask values. 

Effect (LONG) - input 
Valid values are: 

Value Description 

0 Input Shape in character mode 

1 Edit Shape in character mode 
Source (PCSDREC) - input 

An address pointing to a Character Shape Determination Record (CSDRec) for the source text. 
(See “Character Shape Determination Record (CSDRec)” on page 2-23 for format.) 

Target (PCSDREC) - output 

An address pointing to a Character Shape Determination Record (CSDRec) for the target text. 
(See “Character Shape Determination Record (CSDRec)” on page 2-23 for format.) 

CSDState (PULONG) - input/output 

The user must set this parameter to zero on initial invocation and not modify it again to preserve 
the CSDState value between invocations, until the shaping of the whole source text is completed. 

Increment (ULONG) - input 

The number of bytes of each character cell. 



Returns 

Return Code (APIRET). NIsEditShape returns the following values: 
0 NOERROR 

672 ERROR_BIDI_INVALID_INCREMENT 

673 ERROR_BIDI_INVALID_COM BINATION 

675 ERROR_BIDI_INVALID_EFFECT 

676 ERROR_BIDI_INVALID_CSDREC 

677 ER ROR_B I D l_IN V ALI D_CSDST ATE 

680 ERROR_BIDI_INVALID_ORIENTATION 

682 ERROR_BIDI_INVALID_CSD 

684 NO_ERROR_BIDI_RW_INCOMPLETE : 
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Remarks 

When this process is used in the input mode ( Effect has a value of 0), it will read the current 
character (pointed to by the Bufferlndex parameter in CSDRec), and its two preceding characters. 
Based on these readings and according to the value of CSDState, the correct shape of the current 
character is determined (the shape of the two preceding characters may change as well) and the 
CSDState may be updated. 

When this process is used in the edit mode (Effect has a value of 1) it will read the current character, 
the three preceding and the two succeeding characters. Based on these readings, the process will 
determine the shape of the current character independent of the value of CSDState. Some of the 
surrounding characters read may also change after shaping. 

The provided data buffers (Source and Target) must not partially overlap, or unpredictable results 
may occur. However, Target and Source may totally overlap. 
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Example Code 

fdefine I NCL_D0SERR0RS 

fdefine INCL_BDCALLS /* This is to include the Bidi headers */ 

finclude <os2.h> 



APIRET RC; 



/* Input string to shape.... */ 

static CHAR string [] = {'A' . 'r' . 'a' . 'b' . 1 i ' . 'c'}; 



/* Assuming that an edit operation */ 
/* happened, and now the character 1 b 1 */ 
/* has incorrect shape */ 



ULONG bidiattr; 

ULONG effect 3 1L; 

PCSDRec Source_and_Target; 
ULONG CsdState=0; 

ULONG Increment =1; 

USHORT i; 



/* Bidi attributes */ 
/* Edit mode shaping to adjust the shape*/ 
/* of the surrounding characters as well*/ 
/* Defining the input / output structure*/ 
/* in case of Edit mode, this value is */ 
/* ignored */ 

/* Dummy counter */ 



bidiattr = BD_LEVEL /* reserved */ 

| BD_SUPPORT /* reserved */ 

| BDORIENT_RTL /* the input string is RTL */ 

I BDNUM_PASSTHRU /* numerics passthru */ 

| BDCSD_AUTOMATIC; /* automatic shaping on */ 



Source_and_Target->RecLength = 16; 



/* 

/* 

/* 

/* 

Source_and_Target->BufferIndex = 3L; 



The current character that we want to*/ 
shape is the ' b 1 , which is element */ 
number 3 (considering that 'A 1 is */ 
element number 0) in the string */ 



/* 

/* 

/* 

Source_and_Target->BufferLength = 6L 



The buffer that we want to shape a */ 
character in it has 6 characters, i.e*/ 
the length =6 */ 



/* Address of the string */ 

Source_and_Target->Buffer = (PCHAR) string; 



RC = NlsEditShape(bidiattr, 
effect, 

Source_and_Target, /* Input structure, containing string*/ 
Source_and_Target, /* Put the output on the same input */ 
/* buffer */ 

SCsdState, 

Increment) ; 

if (RC=NO_ERROR_BIDI_RW_INCOMPLETE) 

printf ("The input/output Buffer are too small to read all the \n"); 
printf ("surrounding characters, the result may not be as expected \n"); 
else if (RC !=0) 

Printf ("RC = %ld\n", RC); 



Here is another example of the same API in Input mode. 



static CHAR string [] 



{'A' 



.'r'.'a 



/* Input string to shape. 

I Ikl 121 I r I I I I c I 14.1 

» u » I > ^ a 1 



*/ 

rViVnVg'}; 
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ULONG bidiattr; 

ULONG effect=0L; 

PCSDRec Source_and_Target; 
ULONG CsdState=0; 



ULONG Increment =1; 

bidiattr = BD_LEVEL 
I BD_SUPPORT 
| BDORIENT_RTL 
| BDNUM_PASSTHRU 
| BDCSD_AUTOMATIC; 

Source_and_Target->RecLength = 16; 

/* The buffer that we want to shape a */ 

/* character in it has 6 characters, i.e*/ 

/* the length =6 */ 

Source_and_Target->BufferLength = strien (string); 

/* Address of the string */ 

Source_and_Target->Buffer = (PCHAR)string; 

for (i=0;i<str1en(string); i++) { 

/* The current character that we want to*/ 

/* shape is first character number zero */ 

/* in the string, then character number */ 

/* one .. and so on */ 

Source_and_Target->BufferIndex = i; 

RC = NlsEditShape(bidiattr, 
effect, 

Source_and_Target, /* Input structure, containing string*/ 
Source_and_Target, /* Put the output on the same input */ 
/* buffer */ 

&CsdState, 

Increment) ; 



/* Assuming that this string is the */ 
/* input from a keyboard, and we shape */ 
/* the character typed according to its */ 
/* previous characters, and the CSDState*/ 

/* Bidi attributes */ 
/* Input mode shaping */ 

/* Defining the input / output structure*/ 
/* Everytime we start to shape a string */ 
/* using input mode, this variable */ 
/* should always be zero, and we should */ 
/* not intend to change this value */ 
/* between calls to this API, until we */ 
/* finish shaping of the string */ 

/* reserved */ 
/* reserved */ 
/* the input string is RTL */ 
/* numerics passthru */ 
/* automatic shaping on */ 



/* The warning message NO_ERROR_BIDI_RW_INCOMPLETE, will occur while / 

/* shaping the characters number zero and one in the string, because */ 

/* they do not have 2 preceding characters. However, in this case, */ 

/* the output will be correct, because the API assumes the unavailable*/ 

/* characters as blanks, and it is a valid assumption in this case */ 

/* Generally you may not need to worry about this warning message. */ 

i f (RC=NO_ERROR_BIDI_RW_INCOMPLETE) 

printf ("The input/output Buffer are too small to read all the \n"); 
printf ("surrounding characters, the result may not be as expected \n"); 
else if (RC !=0) 

Printf ("RC = %ld\n", RC); 

} /* endfor */ 
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NlsInverseString 



#define INCL_BDCALLS 



NlsInverseString (Source, Target, Length, Increment) 



NlsInverseString places the Source string in inverse order into the Target string. 



Parameters 

Source (PCHAR) - input 

Address of the source buffer containing the text to be inverted. 

Target (PCHAR) - output 

Address of the target buffer where the inverted text is written. 

Length (ULONG) - input 

The number of bytes of both the Source and Target buffers. (Both buffers must be the same 
length.) 

Increment (ULONG) - input 

The number of bytes of each character cell. 



Returns 

Return Code (APIRET). NlsInverseString returns the following values: 

0 NO_ERROR 

671 ERROR_BIDI_INVALID_LENGTH 

672 ERROR_BIDI_INVALID_INCREMENT 

673 ERROR_BIDI_INVALID_COMBINATION 

Remarks 

The provided data buffers (Source and Target ) must not partially overlap, or unpredictable results 
may occur. However, Target and Source may totally overlap. 
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Example Code 

#define INCL_D0SERR0RS 

#define INCL_BDCALLS /* This is to include the Bidi header */ 

/* file */ 

finclude <os2.h> 



static UCHAR 

cell string_in [15] = {'S', OxOf, 
1 t 1 , Oxle, 
1 r 1 , 0x49, 
1 i ■ , 0x71, 
1 n 1 , 0x4f, 
'g 1 , 0x2a, 
'1 ',0x0f, 
'\ 0 ' 

}; 

UCHAR cell string_out [15]; 



/* This is the string to reverse, */ 
/* each character is followed by */ 
/* its display attributes, as if it */ 
/* is a part of the text display */ 
/* buffer */ 



/* This is where the inverted string */ 
/* will be written */ 



ULONG length; 
ULONG incr; 

API RET RC; 



/* Length of character to be inverted*/ 
/* Number of bytes to increment for */ 
/* next char */ 
/* Error returned */ 



length = strlen(cell stri ng_i n) ; 
incr = 2; 



RC = NlsInverseString(cell string_in, cell string_out, length, incr); 
if (RC != 0) { 

printf("\n\nError in inverting.\n") ; 
exit(l) ; 
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#define INCL_BDCALLS 



NIsQueryBidiAtt (Effect, Retlnfo) 



NIsQueryBidiAtt returns bidirectional information about this session. 



Parameters 

Effect (LONG) - input 

A value that defines the bidirectional control block information to be returned in the Retlnfo data 
buffer. Valid values are: 

Value Description 

-1 Retlnfo has the format of BDKVCB (Bidirectional Keyboard/Video Control Block) and 

contains the default bidirectional support values. 

0 Retlnfo has the format of BDKVCB (Bidirectional Keyboard/Video Control Block) and 

contains the current values. 

Note: For Effect values of —1 or 0 the length field of the Bidirectional 
Keyboard/Video Control Block is processed as follows: 

Length less than 2 

An ERROR_BIDI_INVALID_LENGTH is returned. 

Length equal 2 The actual length is returned within the Length field 

Length greater than 2 and less than actual field 

The first length bytes of the control block are returned. 

Length greater than or equal actual length of control block 

The control block data and the updated Length field value (actual 
control block length) are returned. 

1,2,3 Retinfo has the format of the Bidirectional Printer Control Block (BDPRCB). See 
“Bidirectional Printer Control Block" on page 2-21 for format. 

The Effect value determines which printer ID the requested data is for. (LPT1 is 
represented by 1, LPT2 by 2, and LPT3 by 3.) The required input length parameter 
value is 10 bytes. 

Retlnfo (PRETINFO) - input/ output 

Address of a data buffer where the return information is written. The first field of the buffer is 
Length (USHORT). On input, the length field value, as well as remaining buffer format, are 
defined by the Effect parameter. On output, the Length field indicates the actual amount of data 
written or required for the Effect parameter request. 



Returns 

Return Code (APIRET). NIsQueryBidiAtt returns the following values: 

0 NO_ERROR 

671 ERROR_BIDI_INVALID_LENGTH 

675 ERROR_BIDI_INVALID_EFFECT 

683 ERROR_BIDI_NO_SUPPORT 
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Example Code 

#define INCL_D0SERR0RS 

#define INCL_BDCALLS /* This is to include the Bidi headers 
finclude <os2.h> 



*/ 



BDKVCB ses_attr; /* Structure needed to query the session attributes */ 

BDPRCB prt_attr; /* Structure needed to query the printer attributes */ 



API RET RC; 



/* Used for error checking 



*/ 



/* To query the Bidi attributes only... */ 

ses_attr.BDLength = 8; 
prt_attr.PRLength = 6; 

/* This is the call to query the bidi attributes of the session */ 

RC= NlsQueryBidiAtt( 0L, (PRETINFO)&ses_attr); 



i f (RC == 0) 

printf("The Bidi attributes of this session are %lx“,ses_attr.BDAtts); 
else { 

printf("Error ... cannot Query rc = %ld\n",rc); 
return; 

} 

/* This is the call to query the bidi attributes of the printer LPT1 */ 
RC= NlsQueryBidiAtt( 1L, (PRETINFO)&prt_attr) ; 



i f ( RC == 0) 

printf("The Bidi attributes of this session are %lx",prt_attr.PRAtts); 
else { 

printf("Error ... cannot Query rc = %ld\n",rc); 
return ; 

} 
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^define INCL_BDCALLS 



NIsSetBidiAtt (Effect, Setlnfo) 



NIsSetBidiAtt sets the bidirectional information for this session. 

Parameters 

Effect (LONG) - input 

A value that defines the bidirectional control block information being updated by the Setlnfo data 
buffer. Valid Effect values are: 

Value Description 

—1 Setlnfo has the format of BDKVCB (Bidirectional Keyboard/Video Control Block) and 

accesses the default bidirectional support values. See “Bidirectional Control Block” 
on page 2-20. 

0 Setlnfo has the format of BDKVCB (Bidirectional Keyboard/Video Control Block) and 

accesses the currently active bidirectional support values. See “Bidirectional 
Control Block” on page 2-20. 

Note: For Effect values of —1 or 0 the length field of the Bidirectional 
Keyboard/Video Control Block is processed as follows: 

Length less than or equal 4 

An ERROR_BIDI_INVALID_LENGTH is returned. 

Length greater than 4 and less than actual length 

The first Length bytes of the caller provided control block 
are copied into the specified system control block. 

1, 2, 3 Setlnfo has the format of BDPRCB (Bidirectional Printer Control Block). The Effect 
value determines which printer ID the requested data is for. (LPT1 is represented by 
1, LPT2 by 2, and LPT3 by 3.) 

Setlnfo (PRETINFO) - input/output 

Address of the process-supplied data buffer containing the information to be updated in the 
specified Bidirectional Control Block. The required length field size values are defined by both 
the Effect parameter value and its associated Bidirectional Control Block. 



Returns 

Return Code (APIRET). NIsSetBidiAtt returns the following values: 

0 NO_ERROR 

671 ERROR_BIDI_INVALID_LENGTH 

674 ERROR_BIDI_INVALID_RESERVED 

675 ERROR_BIDI_INVALID_EFFECT 

678 ERROR_BIDI_INVALID_LEVEL 

679 ERROR_BIDI_INVALID_TYPE_SUPPORT 

680 ERROR_BIDI_INVALID_ORIENTATION 

681 ERROR_BIDI_INVALID_NUM_SHAPE 

682 ERROR_BIDI_INVALID_CSD 

683 ERROR_BIDI_NO_SUPPORT 

+ SYSTEM ERRORS 
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NIsSetBidiAtt 



Example Code 

#define I NCL_D0SERR0RS /* Including the system return codes, will */ 

/* include the bidi return error codes as well */ 
fdefine INCL_BDCALLS /* This to include the Bidi header file */ 

finclude <os2.h> 



BDKVCB ret_attr; 



API RET RC; 



/* Define the area where we will get the result*/ 
/* of what we want to query from the session */ 
/* used for error checking */ 



ret_attr.BDLength = 8; /* The length here is 8 to query only on the */ 

/* Bidi attribute. */ 

RC = NlsQueryBidiAtt( 0L, (PRETINFO)&ret_attr) ; 



i f (RC != 0) 

{ 

printf("\n\nError in query the Bidi Attributes RC=%ld\n",RC) ; 
return ; 



/* Here we force the orientation in the Bidi 
/* attribute, to be RTL 



*/ 

*/ 



ret_attr.BDAtts = ret_attr. BDAtts | BDORIENT_RTL; 

/* Now let's set the session Bidi attributes */ 
/* with the new value */ 



RC = NlsSetBidiAtt( 0L, (PSETINFO)&ret_attr); 
if( RC != 0) 

{ 

printf("\n\nCannot set the session Bidi Attributes RC=%ld\n",RC) ; 
return; 

} 
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NIsSetBidiPrint 



#define INCL_BDCALLS 



NIsSetBidiPrint (BidiAtts, Length, FlleHandle) 



NIsSetBidiPrint assigns the bidirectional attributes to a specified printer, and adds the appropriate 
printer codes to override the current bidirectional attributes of the printer. 

Parameters 

BidiAtts (ULONG) - input 

A bit mask containing the possible bidirectional attributes. See “Bidirectional Attributes Bit 
Mask” on page 2-22 for mask values. 

Length (ULONG) - input 
This value must be 8. 

FlleHandle (HFILE) - input 

The handle of the device/file that will have the generated printer codes added to it. 

Returns 

Return Code (APIRET). NIsSetBidiPrint returns the following values: 

0 NO_ERROR 

671 ERROR_BIDI_INVALID_LENGTH 

674 ERROR_BIDI_INVALID_RESERVED 

678 ERROR_BIDI_INVALID_LEVEL 

679 ERROR_BIDI_INVALID_TYPE_SUPPORT 

680 ERROR_BIDI_INVALID_ORIENTATION 

681 ERROR_BIDI_INVALID_NUM_SHAPE 

682 ERROR_BIDI_INVALID_CSD 

683 ERROR_BIDI_NO_SUPPORT 

+ FILE SYSTEM ERRORS 

Remarks 

You can issue NIsSetBidiPrint only after the printer has been opened, so that there is a valid handle 
available. 
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NIsSetBidiPrint 



Example Code 

#define INCL_D0SERR0RS /* Including the system. return codes, will */ 

/* include the bidi return error codes as well */ 
#define INCL_BDCALLS /* This to include the Bidi header file */ 

#include <os2.h> 

static CHAR string [] = {'A' , 'r' , 'a' , 'b' ,'i 1 , 'c'}; 

/* RTL string to print */ 

APIRET RC; /* The return code from the API */ 

FILE * FileHandle; /* File handle passed to the API */ 

ULONG bidiattr; /* Bidi attributes */ 

ULONG length=8; /* This is reserved and always =8 */ 

USHORT j; /* Duirniy counter */ 

bidiattr = BD LEVEL /* Reserved */ 

| BDJUPPORT /* Reserved */ 

j BDORIENT_RTL /* The required orientation to print. */ 

| BDNUM_PASSTHRU /* Numerics passthru, no conversion */ 

j BDCSD_AUTOMATIC; /* Automatic shaping on */ 



FileHandle = fopen("LPTl", "wb"); 

if (FileHandle == NULL) { 

printf( "Cannot open the Printer\n"); 
return; 

} 



RC = NlsSetBidi Print (bidiattr, length, (HFILE)Fil eHandl e->_f i 1 e) ; 
if (RC) 

printf ("Error in sending string attributes to the printer RC=%ld\n",RC); 
else 

/* Send the Bidi attributes of the */ 
/* Following string to print */ 

fputs (string, FileHandle); 

fclose(FileHandle) ; /* Close the printer */ 
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N IsShape B id iStri ng 



^define INCL_BDCALLS 



NIsShapeBidiStrlng (BldiAtts, Reserved, Source, Target, Length, Increment) 



NIsShapeBidiString shapes a text string according to the value of the CSD byte in the bidirectional 
attributes bit mask. 

Parameters 

BldiAtts (ULONG) - input 

This parameter is a bit mask containing the possible bidirectional attributes. See “Bidirectional 
Attributes Bit Mask” on page 2-22 for mask values. 

Reserved (ULONG) - input 
Must be zero. 

Source (PCHAR) - input 

Address of the source buffer containing the text to be shaped. 

Target (PCHAR) - output 

Address of the target buffer where the shaped text or returned character shape text is written. 

Length (ULONG) - input 

The number of bytes of both the Source and Target buffers. (Both buffers must be the same 
length.) 

lncrement(ULONG) - input 

The number of bytes of each character cell. 



Returns 

Return Code (APIRET). NIsShapeBidiString returns the following values: 

0 NO_ERROR 

671 ERROR_BIDI_INVALID_LENGTH 

672 ERROR_BIDI_INVALID_INCREMENT 

673 ERROR_BIDI_INVALID_COMBINATION 

674 ERROR_BIDI_INVALID_RESERVED 

680 ERROR_BIDI _INVALID_ORIENTATION 

682 ERROR_BIDI _INVALID_CSD 

Remarks 

The provided data buffers (Source and Target) must not partially overlap, or unpredictable results 
may occur. However, Target and Source may totally overlap. 
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NIsShapeBidiString 



Example Code 

Idefine INCL_D0SERR0RS 

Idefine INCL_BDCALLS /* This is to include the Bidi headers */ 

linclude <os2.h> 

APIRET RC; 

static CHAR string [] = {'A'.'r'.'a'.'b'.'i'.'c'}; 

/* Input string to shape */ 

ULONG bidiattr; /* Bidi attributes */ 

ULONG effect=0L; /* reserved */ 

CHAR target [6]; /* Shaped string is returned here */ 

ULONG length; /* length of string to be shaped */ 

ULONG increment ; /* number of bytes to increment between */ 

/* each character */ 

length = strlen(string) ; 
increment = 1; 

bidiattr = BD_LEVEL /* reserved */ 

| BD_SUPPORT /* reserved */ 

| BDORIENT_RTL /* the input string is RTL */ 

I BDNUM_PASSTHRU /* numerics passthru */ 

j BDCSD_AUTOMATIC; /* Automatic shape determination on */ 

RC=N1 sShapeBi di Stri ng (bi di attr , effect , stri ng , 

target, length, increment); 

i f (RC != 0) /* check for error */ 

printf ("RC=%1 d\n",RC) ; 
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Bidirectional Control Block 

This control block exists for each full screen session created to hold the bidirectional attributes of 
this session. The attributes can change by either the NIsSetBidiAtt function or by the keyboard 
pop-up utility. 

Size Field 

USHORT BDLength - length of the control area in bytes, including the length field itself. 

USHORT BDVersionld - identifier of the bidirectional version. This value is hex 10. 

ULONG BDAtts - bidirectional attributes. (See “Bidirectional Attributes Bit Mask” on 
page 2-22.) 

USHORT BDHotkeyFlags - flags for enabling/disabling the bidirectional hotkeys. (For each flag, 0 
means enable the hotkey, 1 means disable the hotkey.) 



Flaa bit 


Description 


15 


Reserved 


14 


Shape Isolated 


13 


Shape Final 


12 


Shape Middle 


11 


Shape Initial 


10 


Automatic Shaping 


9 


Bidirectional Pop-Up 


8 


Reserved 


7 


Reserved 


6 


Screen Reverse 


5 


Field Reverse 


4 


Auto Push 


3 


End Push 


2 


Push 


1 


Reserved 


0 


Reserved 



2-20 



Bidirectional National Language Support 




USHORT BDFIags - flags to indicate and/or activate some functions. 

Flag Bit Description 

5 BDFieldRev - the normal field orientation is inverted. (Query only) 

4 BDKbdLayer - 0 means Latin, 1 means National Language (NL). (May be 

set or queried) 

3 Reserved must be zero. 



2 BDPushLev - Push level 0 or 1, 0 means no push operation started, 1 

means inverted segment (Latin within National Language). 

1 BDAutoPushL - Auto push flag for left-to-right. 0 means off, 1 means on. 

(May be set or queried) 

0 BDAutoPushR - Auto push flag for right-to-left. 0 means off, 1 means on. 

(May be set or queried) 



Bidirectional Printer Control Block 



This control block exists for each session created to hold the bidirectional printer attributes of this 
session. 



Size Field 

USHORT PRLength - length of the control block 

ULONG PRAtts - bidirectional attributes 

ULONG Reserved - must be zero. 
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Bidirectional Attributes Bit Mask 



Level 

The value of byte 3, bits 4-7: 

4-15 Reserved 
3 Session screen 

0- 2 Reserved 

Support Type 

The value of byte 3, bits 0-3: 

1- 15 Reserved 

0 Visual 

Orientation 

The value of byte 2, bits 0-7 

2 - 255 Reserved 

1 Right-to-left (RTL) 

0 Left-to-right (LTR) 

Numeral Shape 

The value of byte 1, bits 4-7: 

3-15 Reserved 

2 Hindi - numerics represented as code points (hex BO to hex B9) 

1 Passthru - no numeric shaping is performed 

0 Arabic - this value is used to pass between functions only (not valid for setting the 
sessions attributes). Numerics represented as code points (hex 30 to hex 39) 

The value of byte 1, bits 0-3: 

0-3 Reserved 

Character Shape Determination 

The value of byte 0, bits 0-7: 

21-255 
20 
19 
18 
17 
16 

2- 15 

1 
0 



Reserved 
Isolated shapes 
Final shapes 
Middle shapes 
Initial shapes 
Base shapes 
Reserved 
Passthru 

Automatic Shape Determination (ASD) on 



2-22 Bidirectional National Language Support 




Character Shape Determination Record (CSDRec) 

The Character Shape Determination Record has the following format: 

RecLength (ULONG) The size in bytes of the CSDRec. This value is hex 10. 

Buffer (PCHAR) The address of the record text buffer. 

BufferLength (ULONG) The size of the text buffer i n bytes. 

Bufferlndex (ULONG) The index into the text buffer for the current character to process. 



Chapter 2. Bidirectional Functions 2-23 




2-24 Bidirectional National Language Support 




Chapter 3. The User Interface 



This chapter describes the keyboard service functions that provide bidirectional support. This 
chapter also describes the different printing options available to the user. 



Keyboard Services 

The following table shows the hotkeys for online editing. 



Function 


Key Combinations and Names 


Key Numbers 


National Language Keyboard 
Layer 


Alt + right Shift 


60/62 + 57 


Latin Keyboard Layer 


Alt + left Shift 


60/62 + 44 


Screen Reverse 


Alt + New Line/Enter (See 
Note) 


60/62 + 43 


Field/Line Reverse 


Alt + Num Lock 


60/62 + 90 


Push 


Shift + Num Lock 


44/57 + 90 


End Push 


Shift + “/” (on numerical 
keypad) 


44/57 + 95 


Auto Push 


Alt + “/” (on numerical 
keypad) 


60/62 + 95 


National Language Pop-Up 
Indicator 


Alt + Scroll Lock 


60/62 + 125 


Automatic Shape 
Determination / Base toggle 


Alt + “4” (on numerical 
keypad) 


60/62 + 92 


Shape - Isolated 


Alt + “2" (on numerical 
keypad) 


60/62 + 98 


Shape - Initial 


Alt + “1” (on numerical 
keypad) 


60/62 + 93 


Shape - Middle 


Alt + “7” (on numerical 
keypad) 


60/62 + 91 


Shape - Final 


Alt + “8” (on numerical 
keypad) 


60/62 + 96 



Note: The New Line key for the Screen Reverse Function is the Enter key on the 101-key keyboard 
and the New Line key on the 102-key keyboard. 

National Language Keyboard Layer Selection Function 

The bidirectional keyboard has two language layers, a Latin language layer and a National Language 
layer. Latin language layer is the default active language layer. This function is used to set the 
active language to the National Language. 

Note: The language layer selection function does not cause a change in the cursor direction. Text 
continues to be typed in the same direction (unless AUTO PUSH is active). 

In Arabic configuration all the characters typed will be passed to the application in “Base” 
shapes (unless in Push or Field Reverse mode) and will be displayed according to the screen 
attributes. 
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Latin Keyboard Layer 

This function sets the active keyboard language layer to Latin. 



Screen Reverse 

This function causes the alphanumeric layer of the screen image to be symmetrically inverted. The 
screen orientation is reversed from left-to-right to right-to-left, or the other way around. 

When the screen orientation is reversed, the language layer is changed automatically to the default 
language of the screen orientation. For example, if the screen is reversed to right-to-left the 
language layer is changed to the National Language. If the screen is reversed to left-to-right, the 
language layer is changed to Latin. 

When the screen is reversed to right-to-left, the progression of the text and the cursor movement will 
be from right to left, top to bottom. Character Shape Determination (CSD) may get activated. When 
the screen is reversed to left-to-right, the progression of the text and the cursor movement will be 
from left-to-right, top-to-bottom. 



Field Reverse 

The term field is defined as an area on the screen which spans on one line, and delimited by a 
change in the character attributes. The field reverse function is used to achieve a field orientation 
that is opposite to the screen orientation. When this function is invoked, the typing direction will be 
the opposite of the screen orientation. The language layer is changed automatically to the default 
language of the new orientation. If it is right-to-left, the language layer is changed to the National 
Language, if it is left-to-right, the language layer is changed to Latin. 

If this function is invoked while the cursor is under a blank character, the cursor moves to the other 
end of the field, and text entry will start from there. If this function is invoked while the cursor is on a 
non-blank character the cursor remains in the same position, and allows correction of reversed text. 

When this function is activated, and the resulting field is right- to-left, Character Shape Determination 
(CSD) is activated. 



Push 

This function allows the user to enter and correct text in reversed orientation to that of the 
surrounding text. 

This function starts a segment of reversed text. The text is entered in an inserted mode toward the 
end of the field, and the cursor remains stationary. The language layer is changed automatically to 
the default language of the new orientation. For example, if it is inserting to the right, the language 
layer is changed to the National Language. If it is inserting to the left, the language layer is changed 
to Latin. Character Shape Determination (CSD) is also activated. 

Only one level of nesting is supported. If Push is activated again, it is ignored. 

Note: In Arabic configuration, the NL Pop-Up Indicator can be called while being in Push or Field 

Reverse, accordingly one can select different shaping modes to type. However, if the Push or 
Field Reverse is ended while the screen attribute is “Automatic” or “Base” shapes, then the 
characters typed are going to go to the application in their base shapes. If the Push or Field 
Reverse is ended while the screen attribute is anything other than “Automatic” or “Base” 
shapes, the characters are going to the application in full shapes (as is). This is very useful 
as a host emulation mode when storage of shaped characters is needed. In conclusion, there 
are two meaningful CSD settings to end the Push or Field Reverse : 

Automatic In this mode the characters will be stored in base shapes and will be displayed 
shaped. 

Passthru In this mode the characters will be stored and displayed in full shapes. 
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End Push 

This function terminates the current segment of reversed text. The cursor moves to the end of the 
segment, and its direction is restored. 



Auto Push 

This function assists the user in typing mixed right-to-left and left-to-right with increased speed. 

When this function is enabled, Push and End Push are automatically enabled based on the language 
of the text that is being entered. For example, if the screen is left-to-right, and the National Language 
is selected, Push is initiated. When Latin language is selected, End Push is activated automatically. 

National Language Pop-Up Indicator 

The Pop-Up utility is used to view or update the bidirectional attributes as follows: 

• Screen Orientation 

This attribute selects either left-to-right or right-to-left. 

• Language 

This attribute selects either English or Arabic. 

• Auto Push 

This attribute either turns Auto Push on or off. 

• Numeral Shapes 

This attribute allows selection of numeral shapes for entry and presentation. If it is set to Hindi, 
numerals are presented as Hindi numerics (hex BOto hex B9). If it is setto Passthru, numerals 
are presented as they were originally stored or entered from the keyboard. 

In either case, the shapes are encoded to the Arabic numerals (hex 30 to hex 39). 

• Character Shape Determination (CSD) 

The character shape determination does not change the operation of the various function and 
data keys, but rather is considered an inherent part of the Arabic language. This attribute allows 
selection of various shapes: 

- Automatic Shape Determination (ASD) Active 

- Base shapes only 

- Initial shapes only 

- Middle shapes only 

- Final shapes only 

- Isolated shapes only 

- Language Layer 

• Printer 

This attribute selects LPT1, LPT2, or LPT3. 

- LPT orientation 

- Numeral shapes 

- Character Shape Determination 

• Bidirectional Hot Keys 

Some applications may have hot keys which conflict with the bidirectional hot keys and this is a 
way to disable the bidirectional hot keys, and pass the key to the application. However, this will 
not affect the bidirectional services provided because these services can still be set through the 
NL Pop-Up Indicator. 
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Printer Services 

The user can specify different printing options and attributes for LPT1, LPT2, and LPT3. This way, 
each printer can have different attributes that control the way it prints. 

To change the way printing is handled for the same printer, change the attributes for it after all print 
jobs have been completed. This way, any subsequent print jobs will be handled according to the new 
attributes specified. 

When registering the printer support in the RUN command in CONFIG.SYS, you can add some 
arguments to provide more control and memory usage optimization. These arguments are: 

IP: CFGSPEC - is the name of the CFG file that defines the connected printer, for example 

the printing will be incorrect if the connected printer is a QuietWriter 5202 and the CFG 
file stated a 4201 .CFG. The default specification is NONE; no CFG is loaded, and the 
data areas of BDPRTM.EXE are initialized with 4201 Proprinter parameters. A list of the 
CFG files are: 4201. CFG, 4202.CFG, 4202L.CFG, 4207.CFG, 4208.CFG, 4208L.CFG, 

5201 .CFG, 5201L.CFG, 5202.CFG, 5202L.CFG, 5202-Q (5202 in 5201 emulation mode), 
5202-QL (5202 in 5201 emulation mode), 5204.CFG, 5204L.CFG, 4216.CFG, 4216L.CFG, 
4019. CFG, 4019L.CFG. 

10: LPTn is the printer port for which the printer support will be installed. It can be LPT1 , 

LPT2, LPT3. The default is LPT1. 

IV. IANSE - is the initial number of System File Numbers (SFN), or the number of jobs 

being printed simultaneously, to be allocated at startup. An SFN entry is 2KB in size, and 
is used to store the processing context of a printing job. The default and the minimum 
SFN number is 15, the maximum is 128. 

IB: BKT - is the allocation factor by which the printer support will attempt to expand the 

SFN table after it becomes full. The default and the maximum bucket (BKT) size is 15, 
and the minimum is 1. 

All parameters are optional and can be specified in any order. If the printer support detects an error 
in the parameters specified, an error is displayed and the printer support is inactive. 
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Appendix A. Errors 



The following shows the numerical value of an error, its symbolic name, and a brief description of 
the error. 

0 NO_ERROR 

No error occurred. 

671 ERROR_BIDI_INVALID_LENGTH 

A length parameter value of zero was found. 

672 ERROR_BIDI_INVALID_INCREMENT 

An increment parameter value of zero was found. 

673 ERROR_BIDI_INVALID_COMBINATION 

The length of the input and output buffers not a multiple of the increment parameter, and 
or an increment parameter value greater than or not equal the buffer length. 

674 ERROR_BIDI_INVALID_RESERVED 

A reserved parameter found not equal to zero. 

675 ERROR_BIDI_INVALID_EFFECT 

An effect value parameter other than a zero or one was found. 

676 ERROR_BIDI_INVALID_CSDREC 

An invalid parameter within or between the source and target CSDREC structures was 
found. 

677 ERROR_BIDI_INVALID_CSDSTATE 

This error is returned when in input mode and the CSDState is invalid. 

678 ERROR_BIDI_INVALID_LEVEL 

The value of byte 3, bits 4-7 of the Bidirectional Attributes Bit Mask are not set 
correctly. 

679 ERROR_BIDI_INVALID_TYPE_SUPPORT 

The value of byte 3, bits 0-3 of the Bidirectional Attributes Bit Mask are not set 
correctly. 

680 ERROR_BIDI_INVALID_ORIENTATION 

The value of byte 2, bits 0-7 of the Bidirectional Attributes Bit Mask are not set 
correctly. 

681 ERROR_BIDI_INVALID_NUM_SHAPE 

The value of byte 1, bits 4-7 of the Bidirectional Attributes Bit Mask are not set 
correctly. 

682 E R ROR_B I D l_IN V ALI D_CSD 

The value of byte 0, bits 0-7 of the Bidirectional Attributes Bit Mask are not set 
correctly. 

683 ERROR_BIDI_NO_SUPPORT 

Bidirectional support (DLL) not installed or activated. 

684 NO_ERROR_BIDI_RW_INCOMPLETE 

When NIsEditShape function fails to read any of the surrounding characters. This may 
happen because the current character is too close to the buffer boundary. The unread 
characters are assumed to be blank characters, and shaping will carry on accordingly. 
This warning is returned to the user as a notification that the output may not be as 
expected. 



Appendix A. Errors A-1 




A-2 Bidirectional National Language Support 




Index 



A 

ASD toggle 3-1 
Auto Push 3-1, 3-3 

Automatic Shape Determination (ASD) 2-22 

B 

base shape 2-22 
base toggle 3-1 

Bidirectional Attributes Bit Mask 2-22 
Bidirectional Control Block 2-20 
Bidirectional Functions 

NIsConvertBidiNumerics 2-2 
NIsConvertBidiString 2-4 
NIsEditShape 2-6 
NlsInverseString 2-10 
NIsQueryBidiAtt 2-12 
NIsSetBidiAtt 2-14 
NIsSetBidiPrint 2-16 
NIsShapeBidiString 2-18 
Bidirectional Printer Control Block 2-21 
Bit Mask Attributes, Bidirectional 2-22 
BKT 3-4 
bucket 3-4 

c 

CFG 3-4 

Character Shape Determination 2-22 
Character Shape Determination Record (CSDRec) 2-23 
CONFIG.SYS 3-4 
constant names 1-1 



K 

Keyboard Services 3-1 

L 

Latin Keyboard Layer 3-1, 3-2 
Level 2-22 
Line Reverse 3-1 
LPT 3-4 

M 

Middle shape 2-22, 3-1 

N 

National Language keyboard layer 3-1 
National Language Keyboard Layer Selection 
Function 3-1 

National Language Pop-Up indicator 3-1, 3-3 

NIsConvertBidiNumerics 2-2 

NIsConvertBidiString 2-4 

NIsEditShape 2-6 

NlsInverseString 2-10 

NIsQueryBidiAtt 2-12 

NIsSetBidiAtt 2-14 

NIsSetBidiPrint 2-16 

NIsShapeBidiString 2-18 

notation conventions 1-1 

NULL 1-1 

Numeral Shape 2-22 



D 

Determination, Character Shape 2-22 



o 

Orientation 2-22 
Overview 1-2 



E 

End Push 3-1 , 3-3 
Errors A-1 



F 

Field Reverse 3-1, 3-2 
Final shape 2-22, 3-1 
function descriptions 
conventions used 1-1 
notation 1-1 



H 

hot key flags 2-20 



I 

implicit pointer 1-1 
Initial shape 2-22, 3-1 
Isolated shape 2-22, 3-1 



P 

pointer, implicit 1-1 
Printer Services 3-4 
printer support 3-4 
Push 3-1, 3-2 



R 

RUN 3-4 



s 

Screen Reverse 3-1 , 3-2 

SFN 3-4 

Shapes 

automatic determination 2-22 
base 2-22 
final 3-1 
initial 3-1 
isolated 3-1 
middle 3-1 
Support Type 2-22 



Index X-1 




2-22 



T 

Type, Support 



X-2 



Bidirectional National Language Support 




n IBM, OS/2 and Operating System/2 are 
registered trademarks of 
International Business Machines Corporation 



©IBM Corp. 1992 
International Business 
Machines Corporation 

Printed in the 

United States of America 

All Rights Reserved 

10G4433 




siec-4433-ee 



PRINTED IN THE UNITED STATES OF AMERICA 




P10G4433 



